<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>FileOpen</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<style type="text/css">.fopt{width:4em;text-align:center}.fnum{width:4em;text-align:right}</style>
</head>
<body>

<h1>FileOpen <span class="ver">[AHK_L 42+]</span></h1>

<p>Opens a file.</p>
<pre class="Syntax">file := FileOpen(Filename, Flags [, Encoding])</pre>

<h3>Parameters</h3>
<dl>

  <dt>Filename</dt>
  <dd>
    <p>The path of the file to open, which is assumed to be in <a href="../Variables.htm#WorkingDir">A_WorkingDir</a> if an absolute path isn't specified.</p>
    <p><span class="ver">[v1.1.17+]:</span> Specify an asterisk (or two) as shown below to open the standard input/output/error stream:</p>
    <pre>
FileOpen("*", "r")   <em>; for stdin</em>
FileOpen("*", "w")   <em>; for stdout</em>
FileOpen("**", "w")  <em>; for stderr</em></pre>
  </dd>

  <dt>Flags</dt>
  <dd><p>Either <span class="ver">[in AHK_L 54+]</span> a string of characters indicating the desired access mode followed by other options (with optional spaces or tabs in between); or <span class="ver">[in AHK_L 42+]</span> a combination (sum) of numeric flags. Supported values are described in the table below.</p></dd>

  <dt>Encoding</dt>
  <dd><p>The code page to use for text I/O if the file does not contain a UTF-8 or UTF-16 <a href="http://en.wikipedia.org/wiki/Byte_order_mark">byte order mark</a>, or if the <code>h</code> (handle) flag is used. If omitted, the current value of <a href="../Variables.htm#FileEncoding">A_FileEncoding</a> is used.</p></dd>

</dl>
<h3>Flags</h3>
<table class="info">
  <tr><th style="width:4em">&nbsp;</th><th style="width:4em">&nbsp;</th><th style="text-align:left">Access modes (mutually-exclusive)</th></tr>
  <tr><td class="fopt">r</td><td class="fnum">0</td><td><i>Read:</i> Fails if the file doesn't exist.</td></tr>
  <tr><td class="fopt">w</td><td class="fnum">1</td><td><i>Write:</i> Creates a new file, <b style="color:red">overwriting any existing file</b>.</td></tr>
  <tr><td class="fopt">a</td><td class="fnum">2</td><td><i>Append:</i> Creates a new file if the file didn't exist, otherwise moves the file pointer to the end of the file.</td></tr>
  <tr><td class="fopt">rw</td><td class="fnum">3</td><td><i>Read/Write:</i> Creates a new file if the file didn't exist.</td></tr>
  <tr><td class="fopt">h</td><td>&nbsp;</td><td>Indicates that <i>Filename</i> is a file handle to wrap in an object. Sharing mode flags are ignored and the file or stream represented by the handle is not checked for a byte order mark. The file handle is <b>not</b> closed automatically when the file object is destroyed and calling <a href="../objects/File.htm#Close">Close</a> has no effect. Note that <a href="../objects/File.htm#Seek">Seek</a>, <a href="../objects/File.htm#Tell">Tell</a> and <a href="../objects/File.htm#Length">Length</a> should not be used if <i>Filename</i> is a handle to a nonseeking device such as a pipe or a communications device.</td></tr>
  <tr><th>&nbsp;</th><th>&nbsp;</th><th style="text-align:left">Sharing mode flags</th></tr>
  <tr><td class="fopt" style="white-space:nowrap">-rwd</td><td>&nbsp;</td><td>Locks the file for read, write and/or delete access. Any combination of <code>r</code>, <code>w</code> and <code>d</code> may be used. Specifying <code>-</code> is the same as specifying <code>-rwd</code>. If omitted entirely, the default is to share all access.</td></tr>
  <tr><td>&nbsp;</td><td class="fnum">0</td><td>If <i>Flags</i> is numeric, the absence of sharing mode flags causes the file to be locked.</td></tr>
  <tr><td>&nbsp;</td><td class="fnum">0x100</td><td>Shares <i>read</i> access.</td></tr>
  <tr><td>&nbsp;</td><td class="fnum">0x200</td><td>Shares <i>write</i> access.</td></tr>
  <tr><td>&nbsp;</td><td class="fnum">0x400</td><td>Shares <i>delete</i> access.</td></tr>
  <tr><th>&nbsp;</th><th>&nbsp;</th><th style="text-align:left">End of line (EOL) options</th></tr>
  <tr><td class="fopt"><code>`n</code></td><td class="fnum">4</td><td>Replace <code>`r`n</code> with <code>`n</code> when reading and <code>`n</code> with <code>`r`n</code> when writing.</td></tr>
  <tr><td class="fopt"><code>`r</code></td><td class="fnum">8</td><td>Replace standalone <code>`r</code> with <code>`n</code> when reading.</td></tr>
</table>

<h3>Return Value</h3>
<p>If the file is opened successfully, the return value is a <a href="../objects/File.htm">File object</a>.</p>
<p>If the function fails, the return value is 0 and <span class="ver">[in AHK_L 54+]</span> <a href="../Variables.htm#LastError">A_LastError</a> contains an error code.</p>
<p>Use <code>if file</code> or <code>IsObject(file)</code> to check if the function succeeded.</p>

<h3>Remarks</h3>
<p>When a UTF-8 or UTF-16 file is created, a byte order mark is written to the file <b>unless</b> <i>Encoding</i> (or <a href="FileEncoding.htm">A_FileEncoding</a> if <i>Encoding</i> is omitted) contains "UTF-8-RAW" or "UTF-16-RAW".</p>
<p>When a file containing a UTF-8 or UTF-16 byte order mark (BOM) is opened with read access, the BOM is excluded from the output by positioning the file pointer after it. Therefore, <code>File.Position</code> may report 3 or 2 immediately after opening the file.</p>

<h3>Related</h3>
<p><a href="FileEncoding.htm">FileEncoding</a>, <a href="../objects/File.htm">File Object</a>, <a href="FileRead.htm">FileRead</a></p>

<h3>Examples</h3>
<pre class="NoIndent"><a name="writeread"></a><em>; Example: This is a working script that writes some text to a file then reads it back into memory.
; It provides the same functionality as <a href="DllCall.htm#file">this DllCall-example</a>.</em>

FileSelectFile, FileName, S16,, Create a new file:
if (FileName = "")
	return
file := FileOpen(FileName, "w")
if !IsObject(file)
{
	MsgBox Can't open "%FileName%" for writing.
	return
}
TestString := "This is a test string.`r`n"  <em>; When writing a file this way, use `r`n rather than `n to start a new line.</em>
file.Write(TestString)
file.Close()

<em>; Now that the file was written, read its contents back into memory.</em>
file := FileOpen(FileName, "r-d") <em>; read the file ("r"), share all access except for delete ("-d")</em>
if !IsObject(file)
{
	MsgBox Can't open "%FileName%" for reading.
	return
}
CharsToRead := StrLen(TestString)
TestString := file.Read(CharsToRead)
file.Close()
MsgBox The following string was read from the file: %TestString%</pre>

<pre class="NoIndent"><em>; Open the script in read-only mode and read its first line:</em>
file := FileOpen(A_ScriptFullPath, "r")
MsgBox % file.ReadLine()

<em>; Open a console window for this demonstration:</em>
DllCall("AllocConsole")
<em>; Open the application's stdin/stdout streams in newline-translated mode.</em>
stdin  := FileOpen("*", "r `n")  <em>; Requires v1.1.17+</em>
stdout := FileOpen("*", "w `n")
<em>; For older versions:
;   stdin  := FileOpen(DllCall("GetStdHandle", "int", -10, "ptr"), "h `n")
;   stdout := FileOpen(DllCall("GetStdHandle", "int", -11, "ptr"), "h `n")</em>
stdout.Write("Enter your query.`n\> ")
stdout.Read(0) <em>; Flush the write buffer.</em>
query := RTrim(stdin.ReadLine(), "`n")
stdout.WriteLine("Your query was '" query "'. Have a nice day.")
stdout.Read(0) <em>; Flush the write buffer.</em>
Sleep 5000
</pre>
</body>
</html>
